3.3 创建你的第一个 MCP 集成

🎯 本节目标

通过三个递进式的实战案例，你将学会：

✅ 5 分钟： 添加远程 MCP 服务器（无需编程）
✅ 30 分钟： 配置本地 MCP 服务器并使用环境变量
✅ 60 分钟： 构建多服务器集成工作流

📚 示例路线图

示例 1: 远程服务器快速开始 (5 分钟)
  └─ 添加 GitHub MCP 服务器
  └─ OAuth 认证流程
  └─ 创建你的第一个 PR

      ↓

示例 2: 本地服务器配置 (30 分钟)
  └─ 配置 Sequential Thinking 服务器
  └─ 添加 PostgreSQL 服务器
  └─ 环境变量管理

      ↓

示例 3: 完整开发工作流 (60 分钟)
  └─ 多服务器协同（GitHub + Sentry + Linear）
  └─ 端到端自动化故障诊断
  └─ 最佳实践应用

🚀 示例 1：远程 GitHub 服务器（5 分钟）

场景描述

你在开发一个项目，需要 Claude 帮你：

查看最新的 PR 和 Issues
创建新的 PR
评论和更新 Issues

使用 GitHub MCP 服务器，这一切都可以通过自然语言完成。

步骤 1：添加 GitHub 服务器

方式A：使用命令行（推荐新手）

bash

# 添加 GitHub MCP 服务器
claude mcp add --transport http github https://mcp.github.com/anthropic

# 输出：
# ✅ MCP server 'github' added successfully
# ℹ️  Authentication required. Run Claude and use /mcp to login.

方式B：直接编辑配置文件（推荐熟练用户）

编辑 ~/.claude.json，添加：

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/anthropic"
    }
  }
}

步骤 2：启动 Claude 并认证

bash

# 启动 Claude Code
claude

# 在 Claude 中输入
> /mcp

你会看到：

MCP Servers Status:
────────────────────────────────────────
📦 github
   Status: ⚠️  Not authenticated
   Type: HTTP Remote
   URL: https://mcp.github.com/anthropic
   Actions: [Login]
────────────────────────────────────────

点击或输入 "Login"：

浏览器自动打开 GitHub OAuth 页面
授权 Claude Code 访问你的 GitHub
浏览器重定向回 Claude
认证完成！

刷新 /mcp 状态：

MCP Servers Status:
────────────────────────────────────────
📦 github
   Status: ✅ Connected
   Type: HTTP Remote
   URL: https://mcp.github.com/anthropic
   Authenticated as: yourusername
   Tools available: 12
────────────────────────────────────────

步骤 3：使用 GitHub 工具

查看可用工具：

> 你有哪些 GitHub 工具可用？

Claude:
我可以使用以下 GitHub 工具：

1. **github_list_repos** - 列出仓库
2. **github_get_repo** - 获取仓库详情
3. **github_list_issues** - 列出 Issues
4. **github_get_issue** - 获取 Issue 详情
5. **github_create_issue** - 创建新 Issue
6. **github_list_prs** - 列出 Pull Requests
7. **github_get_pr** - 获取 PR 详情
8. **github_create_pr** - 创建新 PR
9. **github_comment_issue** - 评论 Issue
10. **github_comment_pr** - 评论 PR
11. **github_merge_pr** - 合并 PR
12. **github_close_issue** - 关闭 Issue

示例任务 1：列出最新的 Issues

> 列出我的 my-project 仓库中最新的 5 个 issues

Claude: 让我查询一下...
[调用 github_list_issues 工具]

这是 my-project 的最新 5 个 Issues：

1. **#42: 修复登录页面样式问题**
   - 状态：Open
   - 标签：bug, frontend
   - 创建者：teammate
   - 创建于：2 天前

2. **#41: 添加暗黑模式支持**
   - 状态：Open
   - 标签：enhancement, frontend
   - 创建者：you
   - 创建于：3 天前

[...其余 3 个]

示例任务 2：创建新 PR

> 我刚在 feature/dark-mode 分支完成了暗黑模式功能，
  帮我创建一个 PR 合并到 main，标题是 "Add dark mode support"

Claude: 好的，让我创建 PR...

[工具调用确认]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 Tool Call Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tool: github_create_pr
Parameters:
  - repository: my-project
  - title: Add dark mode support
  - head: feature/dark-mode
  - base: main
  - body: Implements dark mode support across the application

Allow this tool call? [Yes / No / Always]

> yes

[调用成功]

✅ PR 创建成功！

🔗 PR #43: Add dark mode support
   https://github.com/username/my-project/pull/43

   From: feature/dark-mode
   To: main
   Status: Open
   Checks: ⏳ Running...

示例任务 3：分析 PR 并提供审查建议

> 审查 PR #43，检查代码质量和潜在问题

Claude: 让我获取 PR 详情并分析代码...

[调用 github_get_pr(pr_number=43)]
[调用 github_get_pr_files(pr_number=43)]

### PR #43 审查报告

**总体评估：** ✅ 代码质量良好，建议合并

**✅ 优点：**
1. 样式实现完整，覆盖所有主要组件
2. 使用 CSS 变量，易于维护
3. 添加了用户偏好存储（localStorage）

**⚠️ 建议改进：**
1. **性能优化：** `ThemeToggle.tsx` 第 15 行
   - 建议：使用 `useCallback` 包装 toggleTheme 函数
   - 原因：避免不必要的子组件重渲染

2. **无障碍访问：** `theme.css` 第 42 行
   - 建议：确保暗黑模式下的对比度符合 WCAG AA 标准
   - 工具：可使用 Chrome DevTools Lighthouse 检查

3. **测试覆盖：** 缺少单元测试
   - 建议：添加主题切换逻辑的测试用例

**🐛 潜在问题：**
无严重问题。建议处理上述改进后合并。

需要我为这些建议添加 PR 评论吗？

学习要点

✅ 远程 MCP 服务器配置非常简单：

一行命令或一段 JSON
OAuth 认证流程自动化
无需管理服务器或 API 密钥

✅ 工具自动发现：

不需要提前知道所有 API 端点
Claude 自动查询可用工具
语义化描述帮助 Claude 正确使用

✅ 用户控制：

每次工具调用都需要确认
可以选择"始终允许"特定工具
安全透明

⚙️ 示例 2：本地服务器配置（30 分钟）

场景描述

你正在开发一个数据驱动的应用，需要：

使用 Sequential Thinking 进行复杂的架构设计
查询本地 PostgreSQL 数据库获取数据
管理敏感的数据库凭据

步骤 1：添加 Sequential Thinking 服务器

什么是 Sequential Thinking？

Sequential Thinking 是一个 MCP 服务器，提供结构化的逐步推理工具，帮助 Claude 更系统地处理复杂问题。

添加配置：

编辑 ~/.claude.json：

json

{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking"
      ]
    }
  }
}

重启 Claude 并验证：

bash

claude
> /mcp

输出：

MCP Servers Status:
────────────────────────────────────────
📦 sequential-thinking
   Status: ✅ Connected
   Type: Local (Stdio)
   Command: npx -y @modelcontextprotocol/server-sequential-thinking
   Tools available: 3
────────────────────────────────────────

测试使用：

> 使用 sequential thinking 设计一个用户认证系统的架构

Claude: 让我使用结构化思维来设计...

[开始 Sequential Thinking 流程]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 Sequential Thinking: 用户认证系统设计
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📍 Step 1: 分析需求
────────────────────────────────────────
- 用户注册和登录
- 多因素认证 (MFA)
- 会话管理
- 密码重置
- OAuth 第三方登录（可选）

✅ 需求分析完成

📍 Step 2: 系统组件设计
────────────────────────────────────────
核心组件：
1. **Authentication Service**
   - 职责：处理登录、注册、token 签发
   - 技术：JWT + Refresh Token

2. **User Management Service**
   - 职责：用户信息 CRUD
   - 数据库：PostgreSQL users 表

3. **MFA Service**
   - 职责：TOTP 验证
   - 库：speakeasy

4. **Session Store**
   - 职责：存储活跃会话
   - 技术：Redis

✅ 组件设计完成

📍 Step 3: 数据库模式设计
────────────────────────────────────────
users 表：
- id (UUID, PK)
- email (VARCHAR, UNIQUE)
- password_hash (VARCHAR)
- mfa_enabled (BOOLEAN)
- mfa_secret (VARCHAR, ENCRYPTED)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

sessions 表：
- id (UUID, PK)
- user_id (UUID, FK)
- refresh_token_hash (VARCHAR)
- expires_at (TIMESTAMP)

✅ 数据库设计完成

[... 继续其余步骤]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Sequential Thinking 完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

总结：设计了一个安全、可扩展的用户认证系统，包含
6 个主要组件、完整的数据库模式和安全最佳实践。

需要我生成详细的技术文档或代码实现吗？

步骤 2：添加 PostgreSQL 服务器

前置准备：

确保你有一个运行中的 PostgreSQL 数据库。

bash

# 检查 PostgreSQL 是否运行
psql --version

# 如果未安装，安装 PostgreSQL
# macOS
brew install postgresql@14
brew services start postgresql@14

# Linux (Ubuntu/Debian)
sudo apt-get install postgresql

# Windows
# 下载安装器：https://www.postgresql.org/download/windows/

创建测试数据库：

bash

# 连接到 PostgreSQL
psql postgres

# 创建数据库和用户
postgres=# CREATE DATABASE test_app;
postgres=# CREATE USER app_user WITH PASSWORD 'secure_password_123';
postgres=# GRANT ALL PRIVILEGES ON DATABASE test_app TO app_user;
postgres=# \q

配置环境变量：

创建 .env 文件（不要提交到 Git！）：

bash

# .env
DATABASE_URL=postgresql://app_user:secure_password_123@localhost:5432/test_app

加载环境变量：

bash

# macOS/Linux
export $(cat .env | xargs)

# 或者添加到 ~/.bashrc / ~/.zshrc
echo 'export DATABASE_URL="postgresql://app_user:secure_password_123@localhost:5432/test_app"' >> ~/.zshrc
source ~/.zshrc

# Windows (PowerShell)
Get-Content .env | ForEach-Object {
  $name, $value = $_ -split '=', 2
  [Environment]::SetEnvironmentVariable($name, $value, 'Process')
}

添加 PostgreSQL MCP 服务器：

编辑 ~/.claude.json：

json

{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    }
  }
}

重启 Claude 并验证：

bash

claude
> /mcp

输出：

MCP Servers Status:
────────────────────────────────────────
📦 sequential-thinking
   Status: ✅ Connected
   Tools: 3

📦 postgres
   Status: ✅ Connected
   Type: Local (Stdio)
   Database: test_app@localhost
   Tools: 5
────────────────────────────────────────

步骤 3：使用 PostgreSQL 工具

创建示例表：

> 使用 postgres 工具创建一个 users 表，包含 id, email, name, created_at 字段

Claude: 让我创建 users 表...

[工具调用]
Tool: postgres_execute
SQL:
  CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  );

Allow? [Yes / No]
> yes

✅ Table 'users' created successfully.

插入测试数据：

> 插入 3 个测试用户

Claude:
[工具调用]
Tool: postgres_execute
SQL:
  INSERT INTO users (email, name) VALUES
    ('alice@example.com', 'Alice'),
    ('bob@example.com', 'Bob'),
    ('charlie@example.com', 'Charlie');

> yes

✅ 3 rows inserted.

查询数据：

> 列出所有用户

Claude:
[工具调用]
Tool: postgres_query
SQL: SELECT * FROM users ORDER BY created_at DESC;

Result:
┌────┬─────────────────────┬─────────┬─────────────────────┐
│ id │ email               │ name    │ created_at          │
├────┼─────────────────────┼─────────┼─────────────────────┤
│ 3  │ charlie@example.com │ Charlie │ 2025-01-15 10:23:45 │
│ 2  │ bob@example.com     │ Bob     │ 2025-01-15 10:23:45 │
│ 1  │ alice@example.com   │ Alice   │ 2025-01-15 10:23:45 │
└────┴─────────────────────┴─────────┴─────────────────────┘

总共 3 个用户。

复杂查询：

> 帮我查询数据库中所有表的名称和行数

Claude:
[工具调用]
Tool: postgres_query
SQL:
  SELECT
    table_name,
    (SELECT COUNT(*) FROM information_schema.tables t2
     WHERE t2.table_name = t1.table_name) as row_count
  FROM information_schema.tables t1
  WHERE table_schema = 'public'
  ORDER BY table_name;

Result:
┌────────────┬───────────┐
│ table_name │ row_count │
├────────────┼───────────┤
│ users      │ 3         │
└────────────┴───────────┘

数据库中有 1 个表，共 3 行数据。

学习要点

✅ Stdio 传输适合本地工具：

直接进程通信，零网络开销
使用标准输入/输出，简单高效
适合数据库、文件系统、本地 API

✅ 环境变量管理敏感信息：

使用 ${VAR} 语法引用环境变量
支持默认值：${VAR:-default}
永远不要把密码硬编码在配置文件里

✅ 工具组合使用：

Sequential Thinking：结构化思维
PostgreSQL：数据访问
两者结合：设计 → 实现 → 验证

🏗️ 示例 3：完整开发工作流（60 分钟）

场景描述

真实场景：生产环境故障诊断

凌晨 2 点，你的手机响了。Sentry 报告生产环境出现大量 500 错误。你需要：

查看 Sentry 错误详情
检查相关代码（GitHub）
查询数据库确认数据状态
在 Linear 中创建 bug issue 跟踪
实施快速修复并创建 hotfix PR

传统方式： 在 5 个不同的工具间来回切换，20+ 分钟

使用 MCP： Claude 自动化整个流程，< 5 分钟

步骤 1：配置多服务器环境

完整配置文件：

编辑 ~/.claude.json：

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/anthropic"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    },
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

认证所有远程服务：

bash

claude
> /mcp

为每个服务完成 OAuth 认证：

GitHub
Sentry
Linear

步骤 2：设置故障诊断 Skill

创建 Skill 封装故障诊断流程：

.claude/skills/production-incident/SKILL.md:

markdown

---
name: production-incident
description: 当用户提到生产环境错误、Sentry 警报或服务中断时，自动诊断问题
allowed-tools:
  - mcp__sentry__*
  - mcp__github__*
  - mcp__postgres__*
  - mcp__linear__*
  - mcp__sequential-thinking__*
---

# 生产环境故障诊断流程

当检测到生产环境问题时，按以下步骤操作：

## 步骤 1：使用 Sequential Thinking 规划诊断

1. 使用 sequential-thinking 工具制定系统化的诊断计划
2. 确定优先级：影响范围 → 严重程度 → 紧急程度

## 步骤 2：收集错误信息（Sentry）

1. 使用 `sentry_list_issues` 获取最新错误列表
2. 使用 `sentry_get_issue` 获取详细错误信息
3. 分析错误堆栈追踪和上下文

## 步骤 3：检查相关代码（GitHub）

1. 根据错误堆栈定位文件
2. 使用 `github_get_file` 获取相关代码
3. 使用 `github_list_commits` 检查最近的代码变更
4. 确定可能的问题原因

## 步骤 4：验证数据状态（PostgreSQL）

1. 使用 `postgres_query` 检查相关数据
2. 确认数据完整性
3. 查找异常数据模式

## 步骤 5：创建跟踪 Issue（Linear）

1. 使用 `linear_create_issue` 创建 bug issue
2. 包含完整的诊断信息
3. 设置优先级和指派人员

## 步骤 6：提供修复建议

1. 基于诊断结果建议修复方案
2. 评估影响和风险
3. 如果用户确认，创建 hotfix PR

## 输出格式

提供结构化的诊断报告：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚨 生产环境故障诊断报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**错误概述：**
[错误类型、发生频率、影响范围]

**根本原因：**
[通过代码、数据库、日志分析得出的结论]

**影响评估：**
[受影响的用户数、功能、严重程度]

**修复建议：**
[具体修复步骤、代码更改、风险评估]

**跟踪 Issue：**
[Linear issue 链接]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

步骤 3：执行故障诊断

触发诊断：

> Sentry 显示大量 500 错误，帮我诊断一下

Claude: 🚨 检测到生产环境问题，启动故障诊断流程...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 Phase 1: 制定诊断计划
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[使用 sequential-thinking]

诊断计划：
1. 获取 Sentry 错误详情 → 确定错误类型和频率
2. 分析错误堆栈 → 定位问题代码
3. 检查最近的代码变更 → 确定引入时间
4. 查询数据库 → 验证数据完整性
5. 创建 Linear issue → 跟踪修复进度
6. 提供修复方案

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Phase 2: 收集错误信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[调用 sentry_list_issues]

最新错误（按频率排序）：

1. **DatabaseError: relation "users_new" does not exist**
   - 发生次数：1,247 次（过去 1 小时）
   - 首次出现：2025-01-15 01:42:03 UTC
   - 最近出现：2 秒前
   - 影响用户：约 850 个独立用户
   - 错误率：23.4% (正常情况 < 1%)

[调用 sentry_get_issue(issue_id=12347)]

堆栈追踪：
  File "/app/api/users.py", line 156, in get_user_profile
    user = db.query("SELECT * FROM users_new WHERE id = %s", user_id)
  File "/app/database.py", line 89, in query
    cursor.execute(sql, params)
  PsycopgError: relation "users_new" does not exist

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Phase 3: 检查代码变更
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[调用 github_get_file(path="api/users.py", ref="main")]

问题代码（api/users.py:156）：
```python
def get_user_profile(user_id):
    # ❌ 问题：表名错误
    user = db.query("SELECT * FROM users_new WHERE id = %s", user_id)
    return user

[调用 github_list_commits(path="api/users.py", limit=5)]

问题 2：OAuth 认证失败

症状：

> /mcp

📦 github
   Status: ⚠️  Authentication failed
   Error: OAuth token expired

解决方案：

步骤 1：清除旧认证

> /mcp
# 选择 GitHub 服务器
# 点击 "Clear authentication"

步骤 2：重新认证

# 点击 "Login"
# 完成浏览器 OAuth 流程

步骤 3：检查权限

确保授予了必要的 scope
GitHub 需要：repo, read:user
Sentry 需要：project:read, event:read

问题 3：工具调用失败

症状：

Claude: [调用 github_create_pr]
❌ Error: Insufficient permissions

解决方案：

A. 检查 OAuth scope

# GitHub 示例
需要的权限：repo (完整仓库访问)
你授予的：public_repo (只有公开仓库)

解决：重新认证并授予正确的 scope

B. 检查工具权限

> /permissions

Allowed tools:
- Read
- Write
❌ mcp__github__create_pr (被阻止)

解决：
> /permissions add mcp__github__create_pr

C. 企业托管配置阻止

json

// /etc/claude-code/managed-mcp.json
{
  "deniedMcpServers": [
    {"serverName": "github"}  // ← 被管理员阻止
  ]
}

// 联系 IT 管理员请求访问

问题 4：配置文件语法错误

症状：

bash

claude
Error: Failed to parse configuration file
SyntaxError: Unexpected token } in JSON at position 142

解决方案：

使用 JSON 验证工具：

bash

# 方式 1：在线验证器
# 复制 ~/.claude.json 内容到 https://jsonlint.com/

# 方式 2：命令行验证
cat ~/.claude.json | python -m json.tool

# 方式 3：VS Code
# 打开 .claude.json，VS Code 自动高亮语法错误

常见语法错误：

json

{
  "mcpServers": {
    "github": {
      "type": "http"   // ❌ 缺少逗号
      "url": "..."
    },
    "postgres": {
      "args": [
        "npx",
        "-y",
        "package"      // ❌ 最后一项不应有逗号（但 JSON5 允许）
      ],
    }   // ❌ 多余的逗号
  }
}

// ✅ 正确
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "..."
    },
    "postgres": {
      "args": ["npx", "-y", "package"]
    }
  }
}

问题 5：上下文窗口污染

症状： Claude 行为不稳定，忽略提示或给出不相关回复。

原因：

加载了太多 MCP 服务器
上下文中有冲突或过时的数据

解决方案：

步骤 1：清除对话历史

> /clear

步骤 2：限制活跃的 MCP 服务器

json

{
  "mcpServers": {
    "github": { "disabled": true },      // 暂时禁用
    "sentry": { ... },                   // 保持启用
    "postgres": { "disabled": true }
  }
}

步骤 3：重启 Claude

bash

# 完全退出
<Ctrl+C> 或 /exit

# 重新启动
claude

问题 6：环境变量展开失败

症状：

MCP Server 'postgres' error:
connection refused to "$DATABASE_URL"

原因： 环境变量未展开，被当作字面字符串。

解决方案：

检查语法：

json

{
  "env": {
    "DB_URL": "${DATABASE_URL}"     // ✅ 正确
    // "DB_URL": "$DATABASE_URL"    // ❌ 错误（缺少花括号）
  }
}

确保环境变量已设置：

bash

# 在启动 Claude 前设置
export DATABASE_URL="postgresql://..."

# 验证
echo $DATABASE_URL

# 启动 Claude
claude

使用默认值：

json

{
  "env": {
    "DB_HOST": "${DB_HOST:-localhost}",  // 如果未设置，默认 localhost
    "DB_PORT": "${DB_PORT:-5432}"
  }
}

✅ 开发最佳实践

1. 从简单开始，逐步扩展

第 1 天：添加 1 个远程服务器（GitHub）
  ↓
第 2 天：添加本地工具（Sequential Thinking）
  ↓
第 3 天：添加数据库（PostgreSQL）
  ↓
第 4 天：组合成工作流

不要一次添加 10 个服务器！ 会导致：

配置混乱
调试困难
上下文污染

2. 使用项目配置共享团队设置

.mcp.json（提交到 Git）：

json

{
  "mcpServers": {
    "project-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postgres-server"],
      "env": {
        "DB_URL": "${PROJECT_DB_URL}"  // 团队共享的环境变量名
      }
    }
  }
}

团队成员的 .env（不提交）：

bash

# 开发环境
PROJECT_DB_URL=postgresql://localhost/dev_db

# 或者测试环境
PROJECT_DB_URL=postgresql://test-db.company.com/test_db

3. 命名约定

清晰的服务器名称：

json

{
  "mcpServers": {
    "github-work": { ... },           // ✅ 明确
    "github-personal": { ... },
    "postgres-prod": { ... },
    "postgres-dev": { ... },

    // ❌ 避免
    "server1": { ... },
    "db": { ... },
    "api": { ... }
  }
}

4. 安全管理凭据

✅ 推荐：

json

{
  "env": {
    "API_KEY": "${MY_SERVICE_API_KEY}",
    "DB_PASSWORD": "${DB_PASS}"
  }
}

❌ 危险：

json

{
  "env": {
    "API_KEY": "sk-1234567890abcdef",     // 泄露风险
    "DB_PASSWORD": "super-secret-pass"
  }
}

最佳实践：

bash

# .env（不提交到 Git）
MY_SERVICE_API_KEY=sk-xxx
DB_PASS=xxx

# .gitignore（确保包含）
.env
.claude.json  # 如果包含敏感信息

5. 使用 `disabled` 临时禁用服务器

json

{
  "mcpServers": {
    "postgres": {
      "disabled": true,  // ← 暂时禁用但保留配置
      "type": "stdio",
      "command": "..."
    }
  }
}

好处：

保留配置
快速切换
调试时隔离问题

6. 监控和日志

启用调试模式：

bash

claude --mcp-debug

查看服务器日志：

> /mcp
# 选择服务器
# 查看 "Recent Logs" 部分

检查上下文使用：

> /context

MCP Servers Token Usage:
- github: 1,234 tokens
- postgres: 567 tokens
- sentry: 890 tokens
Total: 2,691 tokens

7. 版本控制配置

推荐文件结构：

project/
├── .mcp.json               # 团队共享（提交到 Git）
├── .env.example            # 模板（提交到 Git）
├── .env                    # 实际凭据（不提交）
├── .gitignore              # 包含 .env
└── .claude/
    ├── settings.local.json # 个人设置（不提交）
    └── skills/             # Skill 定义（提交）

.env.example：

bash

# 复制这个文件到 .env 并填写实际值

# Database
PROJECT_DB_URL=postgresql://user:password@host:5432/dbname

# APIs
GITHUB_TOKEN=ghp_your_token_here
SENTRY_ORG=your-org

📋 开发检查清单

准备开始使用 MCP 之前，确保：

环境检查：

[ ] Node.js >= 18.17 (node --version)
[ ] Claude Code 已安装并更新
[ ] 了解基本的 JSON 语法

配置检查：

[ ] 配置文件位置正确（~/.claude.json）
[ ] JSON 语法有效（使用验证器检查）
[ ] 环境变量已设置（echo $VAR）
[ ] 敏感信息不在配置文件中

服务器检查：

[ ] 服务器名称清晰明确
[ ] 传输类型正确（HTTP/Stdio）
[ ] 命令和参数正确
[ ] 认证配置完成（对于远程服务器）

测试检查：

[ ] 启动 Claude 无错误
[ ] /mcp 显示所有服务器已连接
[ ] 能够列出工具（"列出所有可用工具"）
[ ] 成功调用至少一个工具

安全检查：

[ ] .env 文件在 .gitignore 中
[ ] 没有硬编码的密码
[ ] OAuth 权限最小化（只请求必要的 scope）
[ ] 文件系统服务器使用 Roots 限制访问

团队协作检查（可选）：

[ ] .mcp.json 提交到版本控制
[ ] .env.example 提供模板
[ ] README 包含设置说明
[ ] 团队成员完成审批流程

🎯 本节核心要点

1. 三种配置方式

方式	适用场景	难度
命令行	快速测试、新手	⭕ 简单
配置文件	生产环境、复杂设置	🟡 中等
项目配置	团队协作	🟡 中等

2. 远程 vs 本地服务器

类型	传输	认证	适用场景
远程	HTTP	OAuth	云服务（GitHub, Sentry）
本地	Stdio	环境变量	数据库、脚本、工具

3. 工作流最佳实践

Skills（流程） + MCP（工具） = 强大的自动化

示例：
Skill "production-incident" 定义诊断流程
  → 调用 Sentry MCP 获取错误
  → 调用 GitHub MCP 检查代码
  → 调用 PostgreSQL MCP 查询数据
  → 调用 Linear MCP 创建 issue
  → 端到端自动化完成

4. 调试三步法

1. 检查连接：/mcp
2. 验证配置：claude mcp get <name>
3. 查看日志：claude --mcp-debug

🚀 下一步

恭喜！你已经掌握了 MCP 的核心使用方法。

在 3.4 进阶技巧和最佳实践 中，我们将学习：

高级配置技巧： 多环境管理、条件配置、插件开发
性能优化： Token 管理、上下文效率、并行处理
团队协作策略： Git 工作流、代码审查、CI/CD 集成
调试大师课： 三级调试方法论、常见陷阱、监控仪表盘
安全加固： 企业级权限、数据保护、合规性

准备好进阶了吗？ 让我们探索 MCP 的高级特性！

💡 实践建议： 不要只是阅读，动手实践每个示例。创建一个测试项目，配置 2-3 个 MCP 服务器，尝试执行本章的完整工作流。学习 MCP 最好的方式就是使用它。

3.3 创建你的第一个 MCP 集成 ​

🎯 本节目标 ​

📚 示例路线图 ​

🚀 示例 1：远程 GitHub 服务器（5 分钟） ​

场景描述 ​

步骤 1：添加 GitHub 服务器 ​

步骤 2：启动 Claude 并认证 ​

步骤 3：使用 GitHub 工具 ​

学习要点 ​

⚙️ 示例 2：本地服务器配置（30 分钟） ​

场景描述 ​

步骤 1：添加 Sequential Thinking 服务器 ​

步骤 2：添加 PostgreSQL 服务器 ​

步骤 3：使用 PostgreSQL 工具 ​

学习要点 ​

🏗️ 示例 3：完整开发工作流（60 分钟） ​

场景描述 ​

步骤 1：配置多服务器环境 ​

步骤 2：设置故障诊断 Skill ​

步骤 3：执行故障诊断 ​

问题 2：OAuth 认证失败 ​

问题 3：工具调用失败 ​

问题 4：配置文件语法错误 ​

问题 5：上下文窗口污染 ​

问题 6：环境变量展开失败 ​

✅ 开发最佳实践 ​

1. 从简单开始，逐步扩展 ​

2. 使用项目配置共享团队设置 ​

3. 命名约定 ​

4. 安全管理凭据 ​

5. 使用 disabled 临时禁用服务器 ​

6. 监控和日志 ​

7. 版本控制配置 ​

📋 开发检查清单 ​

🎯 本节核心要点 ​

1. 三种配置方式 ​

2. 远程 vs 本地服务器 ​

3. 工作流最佳实践 ​

4. 调试三步法 ​

🚀 下一步 ​

3.3 创建你的第一个 MCP 集成

🎯 本节目标

📚 示例路线图

🚀 示例 1：远程 GitHub 服务器（5 分钟）

场景描述

步骤 1：添加 GitHub 服务器

步骤 2：启动 Claude 并认证

步骤 3：使用 GitHub 工具

学习要点

⚙️ 示例 2：本地服务器配置（30 分钟）

场景描述

步骤 1：添加 Sequential Thinking 服务器

步骤 2：添加 PostgreSQL 服务器

步骤 3：使用 PostgreSQL 工具

学习要点

🏗️ 示例 3：完整开发工作流（60 分钟）

场景描述

步骤 1：配置多服务器环境

步骤 2：设置故障诊断 Skill

步骤 3：执行故障诊断

问题 2：OAuth 认证失败

问题 3：工具调用失败

问题 4：配置文件语法错误

问题 5：上下文窗口污染

问题 6：环境变量展开失败

✅ 开发最佳实践

1. 从简单开始，逐步扩展

2. 使用项目配置共享团队设置

3. 命名约定

4. 安全管理凭据

5. 使用 `disabled` 临时禁用服务器

6. 监控和日志

7. 版本控制配置

📋 开发检查清单

🎯 本节核心要点

1. 三种配置方式

2. 远程 vs 本地服务器

3. 工作流最佳实践

4. 调试三步法

🚀 下一步